---
id: bundleMode
title: Bundle Mode
sidebar_label: Bundle Mode
---

# Bundle Mode

Bundle Mode is a feature that gives worklets access to your whole JavaScript bundle - meaning that any code that's present in the bundle can be executed in any worklet and on any runtime. This means that 3rd party libraries can be used in worklets without any tricks like patching them with a `'worklet'` directive.

## Setup

Bundle Mode is available from `react-native-worklets` 0.4, but for best experience and up-to-date features we recommend using the latest version of `react-native-worklets` from the `bundle-mode-preview` tag.

```sh
yarn add react-native-worklets@bundle-mode-preview
```

or

```sh
npm i react-native-worklets@bundle-mode-preview
```

### All platforms

To use `react-native-worklets`'s Bundle Mode feature, you need to make the following changes in your repository:

1. **Modify your Babel configuration**. In your `babel.config.js` file, add the following:

   ```javascript
   module.exports = {
     plugins: [
       [
         'react-native-worklets/plugin',
         {
           // highlight-next-line
           bundleMode: true,
         },
       ],
       // Your other plugins...
     ],
   };
   ```

   [Example reference](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app/blob/main/babel.config.js).

2. **Modify your Metro configuration**. In your `metro.config.js` file, apply the config required for the bundle mode. For example:

   ```javascript
   const {
     getDefaultConfig,
     mergeConfig,
   } = require('@react-native/metro-config');
   // highlight-next-line
   const {
     // highlight-next-line
     bundleModeMetroConfig,
     // highlight-next-line
   } = require('react-native-worklets/bundleMode');

   const config = {
     // Your config
   };

   module.exports = mergeConfig(
     getDefaultConfig(__dirname),
     // highlight-next-line
     bundleModeMetroConfig,
     config
   );
   ```

   [Example reference](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app/blob/main/metro.config.js)

3. Apply the necessary package patches from [worklets repository](https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-worklets/bundleMode/patches).

### iOS

1. **Modify your Podfile**. In your `ios/Podfile`, add the following:

```ruby
# top level
ENV['WORKLETS_BUNDLE_MODE'] = '1'
```

[Example reference](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app/blob/main/ios/Podfile#L11)

2. Make sure to reinstall your pods.

### Android

1. Enable building [React Native from source](https://reactnative.dev/contributing/how-to-build-from-source#android).

   [Example reference](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app/blob/main/android/settings.gradle#L8)

2. **Modify your `gradle.properties`**. In your `android/gradle.properties`, add the following:
   ```groovy
   workletsBundleMode=true
   ```
   [Example reference](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app/blob/main/android/gradle.properties#L41)

## Usage

Currently, third party libraries have to be on an allow-list to use them in worklets. This is because some libraries come with side-effects that would break a Worklet Runtime. For instance, a library that imports something from React Native cannot be used in Worklets, because loading a second instance of React Native on another runtime would break your app.

To add a library to the allow-list you only need to change the `workletizableModules` option in Worklets Babel plugin, which is an array of library names. For instance, if you want to use `my-library` on a Worklet Runtime:

```javascript
module.exports = {
  plugins: [
    [
      'react-native-worklets/plugin',
      {
        bundleMode: true,
        // highlight-next-line
        workletizableModules: ['my-library'],
      },
    ],
    // Your other plugins...
  ],
};
```

[Example reference](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app/blob/main/babel.config.js).
